
<html><head>
<title>traverse_grid - flibs</title>
<style type="text/css"><!--
    HTML {
	background: 	#FFFFFF;
	color: 		black;
    }
    BODY {
	background: 	#FFFFFF;
	color:	 	black;
    }
    DIV.doctools {
	margin-left:	10%;
	margin-right:	10%;
    }
    DIV.doctools H1,DIV.doctools H2 {
	margin-left:	-5%;
    }
    H1, H2, H3, H4 {
	margin-top: 	1em;
	font-family:	sans-serif;
	font-size:	large;
	color:		#005A9C;
	background: 	transparent;
	text-align:		left;
    }
    H1.title {
	text-align: center;
    }
    UL,OL {
	margin-right: 0em;
	margin-top: 3pt;
	margin-bottom: 3pt;
    }
    UL LI {
	list-style: disc;
    }
    OL LI {
	list-style: decimal;
    }
    DT {
	padding-top: 	1ex;
    }
    UL.toc,UL.toc UL, UL.toc UL UL {
	font:		normal 12pt/14pt sans-serif;
	list-style:	none;
    }
    LI.section, LI.subsection {
	list-style: 	none;
	margin-left: 	0em;
	text-indent:	0em;
	padding: 	0em;
    }
    PRE {
	display: 	block;
	font-family:	monospace;
	white-space:	pre;
	margin:		0%;
	padding-top:	0.5ex;
	padding-bottom:	0.5ex;
	padding-left:	1ex;
	padding-right:	1ex;
	width:		100%;
    }
    PRE.example {
	color: 		black;
	background: 	#f5dcb3;
	border:		1px solid black;
    }
    UL.requirements LI, UL.syntax LI {
	list-style: 	none;
	margin-left: 	0em;
	text-indent:	0em;
	padding:	0em;
    }
    DIV.synopsis {
	color: 		black;
	background: 	#80ffff;
	border:		1px solid black;
	font-family:	serif;
	margin-top: 	1em;
	margin-bottom: 	1em;
    }
    UL.syntax {
	margin-top: 	1em;
	border-top:	1px solid black;
    }
    UL.requirements {
	margin-bottom: 	1em;
	border-bottom:	1px solid black;
    }
--></style>
</head>
<! -- Generated from file 'traverse_grid.man' by tcllib/doctools with format 'html'
   -->
<! -- Copyright &copy; 2013 Arjen Markus &lt;arjenmarkus at sourceforge dot net&gt;
   -->
<! -- CVS: $Id: traverse_grid.html,v 1.1 2013/06/30 09:44:18 arjenmarkus Exp $ traverse_grid.n
   -->
<body><div class="doctools">
<h1 class="title">traverse_grid(n) 1.0  &quot;flibs&quot;</h1>
<div id="name" class="section"><h2><a name="name">Name</a></h2>
<p>traverse_grid - Traverse an N-dimensional grid of points</p>
</div>
<div id="toc" class="section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="toc">
<li class="section"><a href="#toc">Table Of Contents</a></li>
<li class="section"><a href="#synopsis">Synopsis</a></li>
<li class="section"><a href="#section1">Description</a></li>
<li class="section"><a href="#section2">ROUTINES</a></li>
<li class="section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="synopsis">
<ul class="syntax">
<li><a href="#1"><b class="cmd">call traverse%init( dimensions, max_index )</b></a></li>
<li><a href="#2"><b class="cmd">call traverse%init( max_index )</b></a></li>
<li><a href="#3"><b class="cmd">call coordinates%init( max_index, range )</b></a></li>
<li><a href="#4"><b class="cmd">call coordinates%init( max_index, range )</b></a></li>
<li><a href="#5"><b class="cmd">call sampler%init( max_index, range )</b></a></li>
<li><a href="#6"><b class="cmd">call object%reset</b></a></li>
<li><a href="#7"><b class="cmd">indices = object%indices()</b></a></li>
<li><a href="#8"><b class="cmd">coords = object%coords()</b></a></li>
<li><a href="#9"><b class="cmd">call object%next( indices )</b></a></li>
</ul>
</div>
</div>
<div id="section1" class="section"><h2><a name="section1">Description</a></h2>
<p>The <i class="term">traverse_grid</i> module defines three types with accompanying routines
to traverse a block of grid points through N-dimensional space. The types
have different purposes:</p>
<ul class="itemized">
<li><p>Objects of the type <i class="term">grid_traversing</i> can be used to traverse a grid along all the grid points.
These objects use integer coordinates only.</p></li>
<li><p>The type <i class="term">grid_coordinates</i> traverses a grid along the same grid points
but you can convert the indices to (real) coordinates of the midpoints.</p></li>
<li><p>The type <i class="term">grid_sampler</i> is meant to sample the grid points in a quasi-random way.
It is useful as an alternative to Monte Carlo, because the selected points are more uniformly
distributed. (See the test program for an example.)</p></li>
</ul>
<p>The idea is that the N-dimensional space in question is split up into rectangular cells
with indices running from 0 up to but not including a maximum value. This maximum can
differ per dimension.</p>
<p>Traversing such a grid, for instance a 4 by 3 grid, gives the following ordering of the
points;</p>
<pre class="example">
    2| 9  10  11  12
    1| 5   6   7   8
    0| 1   2   3   4
     +---+---+---+---+
       0   1   2   3
</pre>
<p>That is, the grid points are visited in the shown order, with indices (0,0), (1,0), ...
(0,1), (0,2), ..., (3,2).</p>
<p>All three types can return the raw indices, but the <i class="term">grid_coordinates</i> and <i class="term">grid_sampler</i>
types can also return the actual coordinates (real numbers).</p>
<p>The <i class="term">grid_sampler</i> type samples the grid points using steps of the size of a prime,
so that the whole space is effectively covered in a fairly small number of samples.</p>
</div>
<div id="section2" class="section"><h2><a name="section2">ROUTINES</a></h2>
<p>Each type contains a number of methods:</p>
<dl class="definitions">
<dt><a name="1"><b class="cmd">call traverse%init( dimensions, max_index )</b></a></dt>
<dd><p>Initialise a <i class="term">grid_traversing</i> object with uniform dimensions, that is, each
index runs from 0 to <i class="term">max_index-1</i>.</p>
<dl class="arguments">
<dt>integer <i class="arg">dimensions</i></dt>
<dd><p>The number of dimensions</p></dd>
<dt>integer <i class="arg">max_index</i></dt>
<dd><p>The maximum index for each dimension (actually the index runs up to that value, but
does not reach it)</p></dd>
</dl></dd>
<dt><a name="2"><b class="cmd">call traverse%init( max_index )</b></a></dt>
<dd><p>Initialise a <i class="term">grid_traversing</i> object with different dimensions, that is,
index i runs from 0 to <i class="term">max_index(i)-1</i>.</p>
<dl class="arguments">
<dt>integer, dimension(:) <i class="arg">max_index</i></dt>
<dd><p>The maximum index per dimension. The number of dimensions is equal to the size
of the array.</p></dd>
</dl></dd>
<dt><a name="3"><b class="cmd">call coordinates%init( max_index, range )</b></a></dt>
<dd><p>Initialise a <i class="term">grid_coordinates</i> object with uniform dimensions, that is, each
index runs from 0 to <i class="term">max_index-1</i>. The <i class="term">range</i> argument contains the
minimum and maximum values of the coordinates. The number of dimensions is equal
to the second dimension of <i class="term">range</i> (that is, <i class="term">size(range,2)</i>).</p>
<dl class="arguments">
<dt>integer <i class="arg">max_index</i></dt>
<dd><p>The maximum index for each dimension (actually the index runs up to that value, but
does not reach it)</p></dd>
<dt>real(kind=wp), dimension(2,:) <i class="arg">range</i></dt>
<dd><p>The minimum (<i class="term">range(1,:)</i>) and the maximum (<i class="term">range(2,:)</i>) coordinate per dimension.
This is used to determine the midpoint coordinates of a cell.</p></dd>
</dl></dd>
<dt><a name="4"><b class="cmd">call coordinates%init( max_index, range )</b></a></dt>
<dd><p>Initialise a <i class="term">grid_coordinates</i> object with uniform dimensions, that is,
index i runs from 0 to <i class="term">max_index(i)-1</i>. The <i class="term">range</i> argument contains the
minimum and maximum values of the coordinates. The number of dimensions is equal
to the second dimension of <i class="term">range</i> (that is, <i class="term">size(range,2)</i>), but the
size of <i class="term">max_index</i> should be equal to that.</p>
<dl class="arguments">
<dt>integer, dimension(:) <i class="arg">max_index</i></dt>
<dd><p>The maximum index per dimension</p></dd>
<dt>real(kind=wp), dimension(2,:) <i class="arg">range</i></dt>
<dd><p>The minimum (<i class="term">range(1,:)</i>) and the maximum (<i class="term">range(2,:)</i>) coordinate per dimension.</p></dd>
</dl></dd>
<dt><a name="5"><b class="cmd">call sampler%init( max_index, range )</b></a></dt>
<dd><p>Initialise a <i class="term">grid_sampler</i> object, analogous to the initialisation of a
<i class="term">grid_coordinates</i> object. Both variants are allowed.</p></dd>
<dt><a name="6"><b class="cmd">call object%reset</b></a></dt>
<dd><p>Resets the current point in a <i class="term">grid_traversing</i>, <i class="term">grid_coordinates</i> or
<i class="term">grid_sampler</i> object to the point with indices all zero.</p></dd>
<dt><a name="7"><b class="cmd">indices = object%indices()</b></a></dt>
<dd><p>Returns the indices of the current point in a <i class="term">grid_traversing</i>, <i class="term">grid_coordinates</i> or
<i class="term">grid_sampler</i> object. The receiving variable must be an array of the correct dimension.</p></dd>
<dt><a name="8"><b class="cmd">coords = object%coords()</b></a></dt>
<dd><p>Returns the coordinates of the current point in a <i class="term">grid_coordinates</i> or
<i class="term">grid_sampler</i> object. The receiving variable must be an array of the correct dimension.</p></dd>
<dt><a name="9"><b class="cmd">call object%next( indices )</b></a></dt>
<dd><p>Determine the next point for a <i class="term">grid_traversing</i>, <i class="term">grid_coordinates</i> or
<i class="term">grid_sampler</i> object. The argument <i class="term">indices</i> will contain the indices of this
new point.</p>
<dl class="arguments">
<dt>integer, dimension(:), optional <i class="arg">indices</i></dt>
<dd><p>The indices for the new point.</p></dd>
</dl></dd>
</dl>
</div>
<div id="copyright" class="section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright &copy; 2013 Arjen Markus &lt;arjenmarkus at sourceforge dot net&gt;</p>
</div>
</div></body></html>
